CKM_ECDH1_DERIVE

This section provides a summary of CKM_ECDH1_DERIVE.

Supported operations

FIPS Mode support

Key size range (bits) and parameters

Parameter

CKM_ECDH1_DERIVE_PARAMS

Mechanism description

The elliptic curve Diffie-Hellman (ECDH) key derivation mechanism, denoted CKM_ECDH1_DERIVE, is a mechanism for key derivation based on the Diffie- Hellman version of the elliptic curve key agreement scheme, as defined in ANSI X9.63, where each party contributes one key pair all using the same EC domain parameters.

This mechanism has a parameter, a CKM_ECDH1_DERIVE_PARAMS structure.

typedef struct CKM_ECDH1_DERIVE_PARAMS {
    CKM_EC_KDF_TYPE kdf;/* key derivation function */
    CKM_ULONG  ulSharedDataLen;/* optional extra shared data */
    CKM_BYTE_PTR pSharedData;
    CKM_ULONG   ulPublicDataLen;/* other party public key value */
    CKM_BYTE_PTR  pPublicData;
} CKM_ECDH1_DERIVE_PARAMS;
typedef struct CK_ECDH1_DERIVE_PARAMS * CKM_ECDH1_DERIVE_PARAMS_PTR;

The fields of the structure have the following meanings:

The mechanism calculates an agreed value using the EC Private key referenced by the base object handle and the EC Public key passed to the mechanism through the pPublicData field of the mechanism parameter.

The length of the agreed value is equal to the ‘q’ value of the underlying EC curve.

The agreed value is then processed by the KDF to produce the CKA_VALUE of the new Secret Key object.

Four main types of KDFs are supported:

• The NULL KDF performs no additional processing and can be used to obtain the raw agreed value. Basically: Key = Z

• The CKF_<hash>_KDF algorithms are based on the algorithm described in section 5.6.3 of ANSI X9.63 2001. Basically: Key = H(Z || counter || OtherInfo)

• The CKF_<hash>_SES_KDF algorithms are based on the variant of the x9.63 algorithm specified in Technical Guideline TR-03111 - Elliptic Curve Cryptography (ECC) based on ISO 15946 Version 1.0, Bundesamt Fur Sicherheit in der Informationstechnik (BSI)

  Basically: Key = H(Z || counter) where counter is a user specified parameter

• The CKF_<hash>_NIST_KDF algorithms are based on the algorithm described in NIST 800-56A Concatenisation Algorithm

  Basically: Key = H(counter || Z || OtherInfo)

The CKF_SES_<hash>_KDF algorithms require the value of the counter to be specified. This is done by arithmetically adding the counter value to the CKF value.

The following Counter values are defined in TR-03111:

Example

To derive a session key to be used as an Alternate key for Encryption the counter must equal 0x00000003. If the SHA-1 hash algorithm is required then the KDF value would be set like this:

CKM_ECDH1_DERIVE_PARAMS Params;
Params.kdf = CKD_SHA1_SES_KDF + CKD_SES_ALT_ENC_CTR;

The supported KDFs are listed below.

CKD_NULL

The null transformation. The derived key value is produced by taking bytes from the left of the agreed value. The new key size is limited to the size of the agreed value. The Shared Data is not used by this KDF and pSharedData should be NULL.

Note

If you are using ProtectToolkit 7.3.0 or newer with ProtectServer 3 HSM Firmware 7.03.00 or newer, this KDF is not available when the FIPS Algorithms Only security flag is set. For more information, refer to FIPS Algorithms Only.

CKD_SHA1_KDF

This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-1 hash algorithm. Shared data can be provided.

Note

If you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer, this KDF is not available when the FIPS Mode security flag is set. For more information, refer to FIPS Mode.

CKD_SHA224_KDF

This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-224 hash algorithm.Shared data can be provided.

Note

If you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer, this KDF is not available when the FIPS Mode security flag is set. For more information, refer to FIPS Mode.

CKD_SHA256_KDF

This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-256 hash algorithm. Shared data can be provided.

Note

If you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer, this KDF is not available when the FIPS Mode security flag is set. For more information, refer to FIPS Mode.

CKD_SHA384_KDF

This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-384 hash algorithm. Shared data can be provided.

Note

If you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer, this KDF is not available when the FIPS Mode security flag is set. For more information, refer to FIPS Mode.

CKD_SHA512_KDF

This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the SHA-512 hash algorithm. Shared data can be provided.

Note

If you are using ProtectToolkit 7.1.0 or newer with ProtectServer 3 HSM Firmware 7.01.00 or newer, this KDF is not available when the FIPS Mode security flag is set. For more information, refer to FIPS Mode.

CKD_RIPEMD160_KDF

This KDF generates secret keys of virtually any length using the algorithm described in X9.63 with the RIPE MD 160 hash algorithm. Shared data can be provided.

Note

This KDF is not available when the FIPS Algorithms Only security flag is set. For more information, refer to FIPS Algorithms Only.

CKD_SHA1_SES_KDF

This KDF generates session keys. It uses the algorithm described in TR-03111 with the SHA-1 hash algorithm. Shared data can be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.

CKD_SHA224_SES_KDF

This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the SHA-224 hash algorithm. Shared data can be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.

CKD_SHA256_SES_KDF

This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the SHA-256 hash algorithm. Shared data can be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.

CKD_SHA384_SES_KDF

This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the SHA-384 hash algorithm. Shared data can be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.

CKD_SHA512_SES_KDF

This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the SHA-512 hash algorithm. Shared data can be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.

CKD_RIPEMD160_SES_KDF

This KDF generates single, double and triple length DES keys that are intended for Encryption operations. It uses the algorithm described in TR-03111 with the Ripe MD 160 hash algorithm. Shared data can be provided but typically it is not used. The counter value that is a parameter to this KDF must be added to this constant.

Note

This KDF is not available when the FIPS Algorithms Only security flag is set. For more information, refer to FIPS Algorithms Only.

CKD_SHA1_NIST_KDF

This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-1 hash algorithm. Shared data should be formatted according to the standard.

CKD_SHA224_NIST_KDF

This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-224 hash algorithm. Shared data should be formatted according to the standard.

CKD_SHA256_NIST_KDF

This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-256 hash algorithm. Shared data should be formatted according to the standard.

CKD_SHA384_NIST_KDF

This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-384 hash algorithm. Shared data should be formatted according to the standard.

CKD_SHA512_NIST_KDF

This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the SHA-512 hash algorithm. Shared data should be formatted according to the standard.

CKD_RIPEMD160_NIST_KDF

This KDF generates secret keys of virtually any length using the algorithm described in NIST 800-56A with the RIPE MD 160 hash algorithm. Shared data should be formatted according to the standard.

Note

This KDF is not available when the FIPS Algorithms Only security flag is set. For more information, refer to FIPS Algorithms Only.

This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.

The following rules apply to the provided attribute template:

• A key type must be provided in the template or else a Template Error is returned.

• If no length is provided in the template, that key type must have a well-defined length. If it doesn’t, an error is returned.

• If both a key type and a length are provided in the template, the length must be compatible with that key type.

• If a DES key is derived with these mechanisms, the parity bits of the key are set properly.

• If the requested type of key requires more bytes than the Key Derive Function can provide, an error is generated.

The mechanisms have the following rules about key sensitivity and extractability:

• The CKA_SENSITIVE, CKA_EXTRACTABLE and CKA_EXPORTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes all take on the default value TRUE.

• If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.

• Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.

Return to ProtectToolkit-C mechanisms.